---
sidebar_position: 20
description: How to configure the relay proxy to serve your feature flags.
---
import {Mandatory, NotMandatory} from "@site/src/components/checks/checks";
import { getIntegrations } from "@site/data/integrations";

# 🔧 Configuration

## Overview
In this page, you will find all the configuration options available for the **relay-proxy**.

The **GO Feature Flag relay-proxy** is highly configurable and can be adapted to your needs.
Despite that you can start with a minimum configuration and fine tune it later.

## Configuration file
The configuration of the **relay proxy** is based on a configuration file that you have to provide.
This is a `yaml` file and usage is to call it `goff-proxy.yaml` but you can name it as you will.

You can provide the configuration file with the option `--config=/path_to_your_file.yaml` when launching the relay proxy.

```shell
go-feature-flag --config=/goff-proxy.yaml
```

:::info
By default, if you omit the `--config` option, the relay proxy will look for a configuration file named `goff-proxy.yaml` in _(int this order)_:
1. `./` _(the current directory)_
2. `/goff/`
3. `/etc/opt/goff/`
:::


## Getting Started
The minimum configuration to start the **relay proxy** is to provide where to retrieve your feature flags configuration.

```yaml title="goff-proxy.yaml"
retrievers:
  - kind: file
    path: /goff/flags.yaml # Location of your feature flag files
```

All the other options are optional and can be added to the configuration file to fine-tune the **relay proxy**.



## Environment variables
The primary way to configure the relay proxy is through a configuration file, but you can also use environment variables if you prefer.  
You can override file configurations using environment variables.

**Here are some things to know when you are using environment variables:**
- To set an option, the environment variable should have the same name as the configuration option in uppercase.  
  For example, to set the `listen` option, you can set the `LISTEN` environment variable.
  ```shell
  export LISTEN=8080
  ```
- If you want to set a nested field, you can use `_` to separate each field.  
  For example, to set the `retrievers` option, you can set the `RETRIEVERS` environment variable.
  ```shell
  export RETRIEVER_KIND=github
  ```
- If you want to set an array of string, you can add multiple values separated by a comma.
  ```shell
  export AUTHORIZEDKEYS_EVALUATION=my-first-key,my-second-key
  ```
- If you are modifying an array of objects, you can use the index to set the value.
  ```shell
  export RETRIEVERS_0_KIND=github
  ```
## Configuration Options
### `retrievers`
This is the configuration on how to retrieve the configuration of the files.
- option name: `retrievers`
- type: [`[]retriever`](#type-retriever)
- default: **none**
- **mandatory: <Mandatory />**
- You can have multiple retrievers at the same time, check [_"Using multiple retrievers"_](../concepts/retriever#using-multiple-retrievers) to see how it works.
- Configuration of a retriever depends on the one you are choosing. Check the [list of retrievers](../integrations/store-flags-configuration#available-retrievers) and go on the detail page of your choice to configure it.

```yaml title="example goff-proxy.yaml"
retrievers:
  - kind: file
    path: /goff/my-flags.yaml
  - kind: s3
    bucket: my-featureflag-bucket
    item: flag/flags.goff.yaml
```

### `startWithRetrieverError`
By default, the **relay proxy** will crash if it is not able to retrieve the flags from the configuration.

If you don't want your relay proxy to crash, you can set `startWithRetrieverError` to true. Until the flag is retrievable the relay proxy will only answer with default values.
- option name: `startWithRetrieverError`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `persistentFlagConfigurationFile`
If set, GO Feature Flag will store the flags configuration in this file to be able to serve the flags even if none of the retrievers is available during starting time.
:::info
By default, the flag configuration is not persisted and stays on the retriever system. By setting a file here, you ensure that GO Feature Flag will always start with a configuration but which can be out-dated.
:::
- option name: `persistentFlagConfigurationFile`
- type: **string**
- default: **none**
- mandatory: <NotMandatory />
- example: `/tmp/goff_persist_conf.yaml`

### `fileFormat`
This is the format of your flag configuration file.

- option name: `fileFormat`
- type: **string**
- Acceptable values are :`yaml`, `json`, `toml`.
- default: **`yaml`**
- mandatory: <NotMandatory />

### `pollingInterval`
This is the time interval **in millisecond** when the relay proxy is reloading the configuration file.
- option name: `pollingInterval`
- type: **int**
- default: **`60000`**
- The minimum time accepted is 1000 millisecond (1 second).
- mandatory: <NotMandatory />

### `enablePollingJitter`
Set to true if you want to avoid having true periodicity when retrieving your flags. It is useful to avoid having spike on your flag configuration storage in case your application is starting multiple instance at the same time.

:::info
We ensure a deviation that is maximum ±10% of your polling interval.
:::
- option name: `enablePollingJitter`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `listen`
This is the port used by the relay proxy when starting the HTTP server.
- option name: `listen`
- type: **int**
- default: **`1031`**
- mandatory: <NotMandatory />

### `monitoringPort`
If set the monitoring endpoints will be served on this specific port.

Check [_"Use specific port for the monitoring"_](./observability#use-specific-port-for-the-monitoring) to have more information.
- option name: `monitoringPort`
- type: **int**
- default: **none**
- mandatory: <NotMandatory />

### `logLevel`
The log level to use for the relay proxy.

Check [_"Logging"_](./observability#logging) to have more information.
- option name: `logLevel`
- type: **string**
- default: **`INFO`**
- Acceptable values are `ERROR`, `WARN`, `INFO`, `DEBUG`.
- mandatory: <NotMandatory />

### `logFormat`
The format to use for structured logs from the relay proxy.

Check [_"Logging"_](./observability#logging) to have more information.
- option name: `logFormat`
- type: **string**
- default: **`json`**
- Acceptable values are `json` and `logfmt`.
- mandatory: <NotMandatory />

### `enablePprof`
This param is used to enable **pprof endpoints** if you wish to enable profiling.

Check [_"Profiling"_](./profiling) to have more information.
- option name: `enablePprof`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `exporter`
Exporter is the configuration used to export data.
- option name: `exporter`
- type: **[exporter](#type-exporter)**
- default: **none**
- mandatory: <NotMandatory />
- Configuration of an exporter depends on the one you are choosing. Check the [list of exporters](../integrations/export-evaluation-data#available-exporters) and go on the detail page of your choice to configure it.

### `notifier`
Notifiers is the configuration on where to notify a flag changes.
- option name: `notifier`
- type: **[notifier](#type-notifier)**
- default: **none**
- mandatory: <NotMandatory />
- Configuration of a notifier depends on the one you are choosing. Check the [list of notifiers](../integrations/notify-flags-changes#available-notifiers) and go on the detail page of your choice to configure it.

### `disableNotifierOnInit`
If `disableNotifierOnInit` is set to **true**, the relay proxy will not call any notifier when the flags are loaded for the 1st time _(during initialization)_. This is useful if you do not want a Slack/Webhook notification saying that the flags have been added every time you start the proxy.
- option name: `disableNotifierOnInit`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `startAsAwsLambda`
Allow to start the relay-proxy as a AWS Lambda, it means that it will start the server to receive request in the AWS format _(see [`awsLambdaAdapter`](#awslambdaadapter) to set the request/response format you are using)_.
Notifiers is the configuration on where to notify a flag changes.
- option name: `startAsAwsLambda`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `awsLambdaAdapter`
This parameter allow you to decide which type of AWS lambda handler you want to use.

- option name: `awsLambdaAdapter`
- type: **string**
- default: **`APIGatewayV2`**
- Acceptable values are `APIGatewayV2`, `APIGatewayV1`, `ALB`.
- mandatory: <NotMandatory />
- This param is used only if `startAsAwsLambda` is `true`.

### `debug`
If `debug` is set to true, we will set the log level to debug and set some components in debug mode (`labstack/echo`, `pprof` etc ...).
- option name: `debug`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `hideBanner`
`hideBanner` can be used to hide the startup banner.
- option name: `hideBanner`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />

### `enableSwagger`
Enables Swagger for testing the APIs directly. If you are enabling Swagger you will have to provide the [`host`](#host) configuration.
- option name: `enableSwagger`
- type: **boolean**
- default: **`false`**
- mandatory: <NotMandatory />
- The Swagger UI will be available at `http://<host>:<listen>/swagger/`.

### `host`
`host` is the DNS you will use to access the relay proxy.
- option name: `host`
- type: **string**
- default: **`localhost`**
- mandatory: <NotMandatory />
- This field is used by Swagger to query the API at the right place.

### `authorizedKeys`
List of authorized API keys.
:::info
If you don't set any API keys, the relay proxy will be fully open to all requests
:::

- option name: `authorizedKeys`
- type: **[authorizedKeys](#type-authorizedkeys)**
- default: **none**
- mandatory: <NotMandatory />

### `evaluationContextEnrichment`
It is a free field that will be merged with the evaluation context sent during the evaluation.

It is useful to add common attributes to all the evaluations, such as a server version, environment, etc.
These fields will be included in the custom attributes of the evaluation context.

:::warning
If in the evaluation context you have a field with the same name, it will be overridden by the `evaluationContextEnrichment`.
:::
- option name: `evaluationContextEnrichment`
- type: **object**
- default: **none**
- mandatory: <NotMandatory />

### `openTelemetryOtlpEndpoint`
Endpoint of your **OpenTelemetry OTLP collector**, used to send traces.

You will be able to forward those traces to your OpenTelemetry solution directly from the collector.
- option name: `openTelemetryOtlpEndpoint`
- type: **string**
- default: **none**
- mandatory: <NotMandatory />

## Configuration Types

### type `authorizedKeys`
`authorizedKeys` is an object were it is possible to configure the list of API Keys that are accepted by the relay proxy.

#### `authorizedKeys.evaluation`
If set, we will check for each evaluation if an authorized key is provided.

Each request will need to provide one of authorized key inside `Authorization` header with format `Bearer <api-key>`.
- option name: `evaluation`
- type: **[]string**
- default: **none**
- mandatory: <NotMandatory />

#### `authorizedKeys.admin`
You need to set API keys in this field if you want to access the `/v1/admin/*` endpoints.

Each request will need to provide one of authorized key inside `Authorization` header with format `Bearer <api-key>`.
- option name: `evaluation`
- type: **[]string**
- default: **none**
- mandatory: <NotMandatory />
- If no api key is configured the endpoint will be unreachable.

#### Example
```yaml title="goff-proxy.yaml"
# ...
authorizedKeys:
  evaluation:
    - "my-first-key"
    - "my-second-key"
  admin:
    - "my-first-admin-key"
    - "my-second-admin-key"
```

### type `retriever`
A [retriever](../concepts/retriever) is the component in charge of loading your flag configuration from a remote source.

#### `retriever.kind`
Configuring a retriever always start by setting the kind of retriever you want to use. This is the only common param between all the retrievers.

- option name: `kind`
- type: **string**
- default: **none**
- mandatory: <Mandatory />

:::info
To find the **`kind`** to use for your retriever and the **rest of the options**, check the [list of retrievers](../integrations/store-flags-configuration#available-retrievers) and go on the detail page of your choice to configure it.

**Available retrievers**:
<ul>
{ getIntegrations("v1.45.0").retrievers.filter(r => r.docLink !== undefined).map((r) => (
  <li key={r.name}><a href={`../integrations/store-flags-configuration/${r.docLink}`}>{r.name}</a></li>
)) }
</ul>
:::

### type `exporter`
An [exporter](../concepts/exporter) is the component in charge of sending your evaluation data to a remote source.

```yaml title="example goff-proxy.yaml"
# ...
exporter:
  kind: s3
  bucket: evaluation-data-bucket
```
:::info
Every `exporter` has its own configuration, check the [list of exporters](../integrations/export-evaluation-data#available-exporters) and go on the detail page of your choice to configure it.

**Available exporters**:
<ul>
  { getIntegrations("v1.45.0").exporters.filter(r => r.docLink !== undefined).map((r) => (
    <li key={r.name}><a href={`../integrations/export-evaluation-data/${r.docLink}`}>{r.name}</a></li>
  )) }
</ul>
:::

### type `notifier`
A [notifier](../concepts/notifier) is the component in charge of sending a notification when a flag changes to a remote system.

```yaml title="example goff-proxy.yaml"
# ...
notifier:
  - kind: discord
    webhookUrl: "https://discord.com/api/webhooks/yyyy/xxxxxxx"
  - kind: slack
    webhookUrl: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
# ...
```
:::info
Every `notifier` has its own configuration, check the [list of notifiers](../integrations/notify-flags-changes#available-notifiers) and go on the detail page of your choice to configure it.

**Available notifiers**:
<ul>
  { getIntegrations("v1.45.0").notifiers.filter(r => r.docLink !== undefined).map((r) => (
    <li key={r.name}><a href={`../integrations/notify-flags-changes/${r.docLink}`}>{r.name}</a></li>
  )) }
</ul>
:::